Skip to content

fix: a clonal lineage that reaches carrying capacity no longer dies for reaching it - #50

Merged
MuteJester merged 5 commits into
masterfrom
engine/lineage-regulation
Nov 5, 2026
Merged

MuteJester merged 5 commits into
masterfrom
engine/lineage-regulation

Conversation

@MuteJester

Copy link
Copy Markdown
Owner

Population regulation inside clonal_lineage() was the discrete logistic map
lambda_base * max(0, 1 - P/n_max) with a hard cap on top. Three things were
wrong with it, and a fourth followed.

Reaching capacity was fatal, with certainty

The cap's break 'generation stopped at next_live.len() == n_max exactly,
so the next generation's 1 - P/n_max was exactly zero, the effective rate was
exactly zero, and every cell drew zero offspring. Not a plateau — a cliff.

Measured across 180 engine runs (n_max in {5,20,50} x lambda_base in
{1.5,2,4} x 20 seeds): 67 reached capacity, 67 went extinct in the following
generation.
Over 40 generations at lambda_base=4.0 every cap hit was fatal
at every capacity tested, 5 through 1000.

The engine's own carrying_capacity_bounds_live_population ran exactly that
configuration — lambda_base=4.0, n_max=200, seed=7, 40 generations — and
asserted peak_live <= n_max and peak_live > n_max/2 on a lineage that had
been extinct since generation 11. It checked the peak and stopped looking.

n_max was never the capacity it is named for

The logistic law settles at n_max * (1 - 1/lambda_base), so a requested 1000
delivered 333 cells at the default lambda_base=1.5, 500 at 2.0, 750 at 4.0.

Above lambda_base=3 there was no settled population at all

The map is past its period-doubling threshold there. Mean-field, n_max=1000:

lambda_base documented actual
1.5 plateau 333, stable
2.5 plateau 600, stable
3.5 plateau cycles 383 / 827 / 501 / 875
4.0 plateau chaotic, 218 to 942

A silent survivorship bias, and advice that caused the failure

allow_extinction=False is the default. A family with no living cells yields no
observed cells, so it is counted extinct and re-grown under a fresh seed up to
50 times — meaning a family that reached capacity was discarded and resampled.
The delivered dataset quietly excluded the clones that expanded most.

When every attempt hit the cap the run raised:

clone 0 went extinct on every one of 50 survival attempts (each founder drew
0 offspring). Increase lambda_base ... so families reliably survive

Both halves wrong. The founders had grown to capacity before being killed, and
raising lambda_base makes a population reach the cap sooner, so following the
advice made it worse. Reproduced through the public API at
lambda_base=8.0, max_generations=40, n_max=200.

The fix

Beverton-Holt: lambda_base / (1 + (lambda_base - 1) * P / n_max).

  • Monotone in P, so it cannot oscillate at any rate.
  • Exactly 1 at P = n_max: a population at capacity replaces itself.
  • Fixed point is n_max itself, which is what the parameter has always claimed.

Measured final population: 1003 for n_max=1000, 204 for 200, 48 for 50 — at
every lambda_base. Sub-replacement growth (lambda_base <= 1) is excluded
rather than damped: there is nothing to regulate, and the denominator would turn
negative past n_max/(1-lambda_base).

The hard cap is gone rather than repaired. A generation may overshoot
capacity — about 6% in practice — and the next one is regulated back below
replacement. Truncating has to choose which cells die, and the previous choice
let vector position decide: it kept the broods of early-indexed parents and
dropped every later parent's brood entire.

Compatibility

DETERMINISM_VERSION 2 -> 3. Every clonal_lineage() and duplex family run
moves; a seed does not carry across the two laws. Plain, corruption and
hypermutation runs are untouched — compared line by line and column by column,
the only field that changed in all six reproducibility goldens is
determinism_version
; every sampled base, call, coordinate and counter is
byte-identical.

n_max now means what it says, so the same n_max yields more cells than
before
— about 3x at the default lambda_base=1.5, with proportional memory
and runtime. To recover the old population, lower n_max: the old plateau was
n_max * (1 - 1/lambda_base).

Tests

The whole clonal suite passed both before and after this change. 784 lineage,
clonal, duplex and determinism tests, and not one asked how many cells were
alive. tests/components/clonal/test_lineage_population_regulation.py adds six
that do; five were verified RED by rebuilding the old law, then restored
byte-identically. Their premise guards are load-bearing twice — a dead lineage
settles at zero and satisfies a one-sided bound, and a seed whose founder never
establishes tests founder luck rather than regulation (a Poisson founder dies
out with probability q = exp(lambda_base(q-1)), about 0.42 at the default).

The replayed capacity fixture was a literal control holding the old law's
arithmetic and caught this exactly as intended: rates 2.25 -> 2.0 and
0.75 -> 1.2, and the child the cap used to suppress is now node 8.

Known gap, deliberately not in this branch

No golden grows a lineage. tests/support/golden.py covers recombination,
corruption and S5F only, which is why only the version stamp moved. A lineage
golden is worth adding, and it is also the artifact the portability question
needs, since the growth path is where exp/ln/powf live and Rust documents
their precision as platform-dependent. If such a golden diverges on macOS or
Windows that is a finding of its own, and it should not arrive as a red CI run
on a defect fix.

Gates

pytest 5862 passed / 17 skipped; performance 9 passed serial; cargo 1737 passed
across 6 suites; ruff clean; inventory gate clean.

…hing it

The regulation law was the discrete logistic map, lambda*(1 - N/n_max),
with a hard cap on top. Three things were wrong with it.

The cap was lethal. `break 'generation` stopped at n_max exactly, so the
next generation's effective rate was lambda*(1 - 1) = exactly zero and
every cell drew zero offspring. Reaching capacity killed the lineage with
certainty: 67 cap hits across 180 runs, 67 extinctions. Over 40
generations at lambda 4 every cap hit was fatal at every capacity tested.
The engine's own carrying-capacity test ran that configuration -- lambda
4, n_max 200, seed 7 -- and asserted a bound on a population that had
been extinct since generation 11.

n_max was not the capacity. The logistic law settles at n_max*(1 - 1/lambda),
so the parameter named a population the lineage never reached: 333 of a
requested 1000 at lambda 1.5.

Above lambda 3 there was no settled population at all. The map is past
its period-doubling threshold there and oscillates -- 383, 827, 501, 875
at lambda 3.5; chaotically between 218 and 942 at lambda 4 -- while the
comment promised a plateau.

Beverton-Holt, lambda/(1 + (lambda-1)*N/n_max), fixes all three. It is
monotone in N, so it cannot oscillate at any lambda, and it is exactly 1
at N = n_max, so a population at capacity replaces itself instead of
dying. Its fixed point is n_max itself, which is what the parameter has
always claimed to be. Sub-replacement growth is excluded rather than
damped: it is already shrinking, and the denominator would turn negative.

The hard cap is gone rather than repaired. A generation may now overshoot
capacity and the next one is regulated back below replacement. Truncating
instead has to choose which cells die, and the cheap choice -- stop at the
first parent that fills the quota -- let vector position decide survival,
keeping early-indexed parents' broods and dropping every later parent's
brood entire. Measured overshoot is about 6%.

The replayed capacity fixture was a literal control holding the old law's
arithmetic, so it caught this exactly as intended. Its rates become 2.0
and 1.2, and the child the cap used to suppress is now node 8.
…s not the mean at affinity 0

The guide gave the logistic formula and said growth "plateaus instead of
exploding". It plateaued at n_max*(1 - 1/lambda_base), not at n_max, and
above lambda_base 3 it did not plateau at all. The parameter table said
the live population "is capped at this"; nothing caps it now, and the cap
was what made reaching capacity fatal. Both say what the law does, and
the guide carries the version-3 note so a reader holding older data knows
which law drew it.

`lambda_base` was documented as the "Poisson mean for offspring count at
affinity 0". A cell's actual mean is lambda_base damped by the live
population and, under selection, scaled by its fitness relative to the
founder -- which at affinity 0 is not generally 1.

The extinction error blamed the founder for drawing zero offspring and
advised raising lambda_base. Under the old law that advice made the
failure more likely. It now names the two real causes, founder extinction
and small-population drift, and gives the founder extinction probability
so the default's 42% is not a surprise.
The lineage regulation law decides what a seed produces, so the version
moves with it. The table row says which law each number means, because a
dataset is only distinguishable from one drawn by the other law by this
stamp.

The six reproducibility goldens change by exactly one field. Compared
line by line and column by column, the only value that differs across
all six is `determinism_version`, 2 to 3: every sampled base, call,
coordinate and counter is byte-identical. The change is confined to
lineage growth, and these fixtures cover recombination, corruption and
S5F -- no golden grows a lineage at all, which is why nothing here
measures the new law. That gap is worth closing separately; it is also
the artifact the portability question needs, since the growth path is
where the engine's transcendental math lives.
The entire clonal suite passed both before and after the regulation law
was replaced. 784 lineage, clonal, duplex and determinism tests, and not
one of them asked how many cells were alive -- they asked what a
lineage's records looked like, which the law barely touches. The only
test that mentioned carrying capacity asserted a bound on the peak, and
an oscillating population satisfies that, as does one that reached
capacity and died twenty-nine generations before the run ended.

Five of these six fail against the old law, which is how they were
written: the settled population came out at n_max*(1 - 1/lambda_base)
rather than n_max for all three rates, every lineage that reached
capacity was extinct at the end, and the last ten generations at
lambda_base 4 spanned better than 4x instead of a few percent.

The premise guards are load-bearing twice over. A dead lineage settles at
zero and would satisfy a one-sided bound, and a seed whose founder never
establishes tests founder luck rather than regulation -- a Poisson
founder dies out with probability q solving q = exp(lambda_base(q - 1)),
about 0.42 at the default 1.5, so the first seed tried failed at two of
the three rates for that reason alone.
The seven entries explained edits from the genotype truth sidecar branch,
which is now in master. A declaration whose change is in the baseline
excuses the next edit to the same name, so the gate asks for them to be
deleted once they have been consumed. This branch needs none of its own:
it adds a test file rather than revising one, and the Rust test renames
are outside the gate's scope.
@MuteJester
MuteJester merged commit d058edd into master Nov 5, 2026
25 of 26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant